package com.example.docmanagement.controller;

import com.example.docmanagement.dto.request.CategoryCreateRequest;
import com.example.docmanagement.dto.response.ApiResponse;
import com.example.docmanagement.dto.response.CategoryResponse;
import com.example.docmanagement.service.CategoryService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

/**
 * 分类管理控制器
 * 提供文档分类的完整管理功能
 * 
 * 基础路径：/api/v1/categories
 * 
 * 主要功能：
 * - 分类列表查询（支持树形和平铺两种模式）
 * - 分类详情查看
 * - 分类创建（支持父子层级）
 * - 分类更新
 * - 分类删除
 * 
 * 特性：
 * - 支持无限层级的树形结构
 * - 自动统计每个分类下的文档数量
 * - 支持排序控制
 */
@RestController
@RequestMapping("/api/v1/categories")
@RequiredArgsConstructor
@Tag(name = "分类管理", description = "分类的增删改查接口")
public class CategoryController {

    private final CategoryService categoryService;

    /**
     * 获取分类列表接口
     * 
     * 接口路径：GET /api/v1/categories
     * 权限要求：无需认证
     * 
     * 功能说明：
     * - 获取所有分类列表
     * - 支持树形结构（默认）和平铺列表两种模式
     * - 树形模式：返回带有children字段的嵌套结构
     * - 平铺模式：返回扁平化的列表，只包含parentId字段
     * 
     * 请求示例（树形模式）：
     * GET /api/v1/categories
     * 
     * 请求示例（平铺模式）：
     * GET /api/v1/categories?flat=true
     * 
     * 响应示例（树形模式）：
     * {
     * "success": true,
     * "data": [
     * {
     * "id": 1,
     * "name": "编程语言",
     * "slug": "programming-languages",
     * "description": "各种编程语言的学习资料",
     * "icon": "code",
     * "parentId": null,
     * "sortOrder": 1,
     * "docCount": 156,
     * "isActive": true,
     * "children": [
     * {
     * "id": 2,
     * "name": "Java",
     * "slug": "java",
     * "parentId": 1,
     * "docCount": 89,
     * "children": []
     * }
     * ]
     * }
     * ],
     * "message": "操作成功"
     * }
     *
     * @param flat 是否返回平铺列表（默认false，返回树形结构）
     * @return 包含分类列表的响应
     */
    @GetMapping
    @Operation(summary = "获取分类列表", description = "返回树形结构的分类列表")
    public ResponseEntity<ApiResponse<List<CategoryResponse>>> getCategories(
            @Parameter(description = "是否返回平铺列表，true 表示扁平结构", example = "false")
            @RequestParam(required = false, defaultValue = "false") Boolean flat) {
        List<CategoryResponse> categories = flat
                ? categoryService.getAllCategoriesFlat()
                : categoryService.getAllCategories();
        return ResponseEntity.ok(ApiResponse.success(categories));
    }

    /**
     * 获取分类详情接口
     * 
     * 接口路径：GET /api/v1/categories/{id}
     * 权限要求：无需认证
     * 
     * 功能说明：
     * - 根据ID获取单个分类的详细信息
     * - 包含该分类的文档统计数据
     * 
     * 请求示例：
     * GET /api/v1/categories/1
     * 
     * 响应示例：
     * {
     * "success": true,
     * "data": {
     * "id": 1,
     * "name": "编程语言",
     * "slug": "programming-languages",
     * "description": "各种编程语言的学习资料",
     * "icon": "code",
     * "parentId": null,
     * "sortOrder": 1,
     * "docCount": 156,
     * "isActive": true,
     * "createdAt": "2024-01-01T00:00:00",
     * "updatedAt": "2024-01-20T10:30:00"
     * },
     * "message": "操作成功"
     * }
     *
     * @param id 分类ID
     * @return 包含分类详细信息的响应
     */
    @GetMapping("/{id}")
    @Operation(summary = "获取分类详情", description = "根据 ID 获取分类详情")
    public ResponseEntity<ApiResponse<CategoryResponse>> getCategory(
            @Parameter(description = "分类ID", required = true, example = "1") @PathVariable Long id) {
        CategoryResponse category = categoryService.getCategoryById(id);
        return ResponseEntity.ok(ApiResponse.success(category));
    }

    /**
     * 创建分类接口
     * 
     * 接口路径：POST /api/v1/categories
     * 权限要求：需要登录认证，需要管理员权限
     * 
     * 功能说明：
     * - 创建新分类
     * - 可以指定父分类创建子分类
     * - 验证slug唯一性
     * - 自动生成创建时间
     * 
     * 请求示例（顶级分类）：
     * POST /api/v1/categories
     * Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
     * Content-Type: application/json
     * 
     * {
     * "name": "编程语言",
     * "slug": "programming-languages",
     * "description": "各种编程语言的学习资料",
     * "icon": "code",
     * "parentId": null,
     * "sortOrder": 1
     * }
     * 
     * 请求示例（子分类）：
     * {
     * "name": "Java",
     * "slug": "java",
     * "description": "Java编程相关文档",
     * "icon": "java-logo",
     * "parentId": 1,
     * "sortOrder": 1
     * }
     * 
     * 响应示例：
     * {
     * "success": true,
     * "data": {
     * "id": 1,
     * "name": "编程语言",
     * "slug": "programming-languages",
     * ...
     * },
     * "message": "分类创建成功"
     * }
     *
     * @param request 分类创建请求，包含名称、slug等信息
     * @return 包含新创建分类信息的响应，HTTP状态码201
     */
    @PostMapping
    @Operation(summary = "创建分类", description = "创建新分类")
    public ResponseEntity<ApiResponse<CategoryResponse>> createCategory(
            @Valid @RequestBody CategoryCreateRequest request) {
        CategoryResponse category = categoryService.createCategory(request);
        return ResponseEntity
                .status(HttpStatus.CREATED)
                .body(ApiResponse.success(category, "分类创建成功"));
    }

    /**
     * 更新分类接口
     * 
     * 接口路径：PUT /api/v1/categories/{id}
     * 权限要求：需要登录认证，需要管理员权限
     * 
     * 功能说明：
     * - 更新现有分类信息
     * - 可以修改父分类（调整层级关系）
     * - 自动更新修改时间
     * 
     * 请求示例：
     * PUT /api/v1/categories/1
     * Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
     * Content-Type: application/json
     * 
     * {
     * "name": "编程开发",
     * "description": "包含各种编程语言和开发工具的学习资料",
     * "sortOrder": 2
     * }
     * 
     * 响应示例：
     * {
     * "success": true,
     * "data": {
     * "id": 1,
     * "name": "编程开发",
     * "updatedAt": "2024-01-21T10:00:00",
     * ...
     * },
     * "message": "分类更新成功"
     * }
     *
     * @param id      分类ID
     * @param request 分类更新请求，包含需要更新的字段
     * @return 包含更新后分类信息的响应
     */
    @PutMapping("/{id}")
    @Operation(summary = "更新分类", description = "根据 ID 更新分类")
    public ResponseEntity<ApiResponse<CategoryResponse>> updateCategory(
            @Parameter(description = "分类ID", required = true, example = "1") @PathVariable Long id,
            @Valid @RequestBody CategoryCreateRequest request) {
        CategoryResponse category = categoryService.updateCategory(id, request);
        return ResponseEntity.ok(ApiResponse.success(category, "分类更新成功"));
    }

    /**
     * 删除分类接口
     * 
     * 接口路径：DELETE /api/v1/categories/{id}
     * 权限要求：需要登录认证，需要管理员权限
     * 
     * 功能说明：
     * - 删除指定分类
     * - 如果分类下有文档，会阻止删除
     * - 如果有子分类，会阻止删除
     * - 物理删除（数据将无法恢复）
     * 
     * 请求示例：
     * DELETE /api/v1/categories/1
     * Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
     * 
     * 响应示例：
     * {
     * "success": true,
     * "data": null,
     * "message": "分类删除成功"
     * }
     *
     * @param id 要删除的分类ID
     * @return 操作成功响应
     */
    @DeleteMapping("/{id}")
    @Operation(summary = "删除分类", description = "根据 ID 删除分类")
    public ResponseEntity<ApiResponse<Void>> deleteCategory(
            @Parameter(description = "分类ID", required = true, example = "1") @PathVariable Long id) {
        categoryService.deleteCategory(id);
        return ResponseEntity.ok(ApiResponse.success(null, "分类删除成功"));
    }
}
